package org.lc.stk.service.course;

import java.util.List;
import java.util.Optional;

import org.lc.stk.model.course.Chapter;
import org.lc.stk.web.dto.chapter.ChapterTreeResponseDTO;

/**
 * 章节服务接口
 */
public interface ChapterService {
    /**
     * 创建章节
     *
     * @param courseId 课程ID
     * @param parentId 父章节ID（可选，为null时创建根章节）
     * @param chapter 章节信息
     * @return 创建的章节
     */
    Chapter createChapter(Integer courseId, Integer parentId, Chapter chapter);

    /**
     * 更新章节信息
     *
     * @param id 章节ID
     * @param chapter 更新的章节信息
     * @return 更新后的章节
     */
    Chapter updateChapter(Integer id, Chapter chapter);

    /**
     * 删除章节
     *
     * @param id 章节ID
     */
    void deleteChapter(Integer id);

    /**
     * 根据ID获取章节
     *
     * @param id 章节ID
     * @return 章节信息
     */
    Optional<Chapter> getChapterById(Integer id);

    /**
     * 获取课程的根章节列表
     *
     * @param courseId 课程ID
     * @return 章节列表
     */
    List<Chapter> getRootChapters(Integer courseId);

    /**
     * 获取子章节列表
     *
     * @param parentId 父章节ID
     * @return 子章节列表
     */
    List<Chapter> getChildChapters(Integer parentId);

    /**
     * 移动章节顺序
     *
     * @param id 章节ID
     * @param newSort 新的排序号
     * @return 更新后的章节
     */
    Chapter moveChapter(Integer id, Integer newSort);

    /**
     * 获取章节的完整路径
     * 例如：第一章/第一节/1.1.1
     *
     * @param id 章节ID
     * @return 章节路径
     */
    String getChapterPath(Integer id);

    /**
     * 检查章节序号在同级中是否已存在
     *
     * @param courseId 课程ID
     * @param parentId 父章节ID
     * @param sort 章节序号
     * @param excludeId 排除的章节ID（用于更新时）
     * @return 是否存在
     */
    boolean isSortExists(Integer courseId, Integer parentId, Integer sort, Integer excludeId);

    /**
     * 获取同级章节中下一个可用的序号
     *
     * @param courseId 课程ID
     * @param parentId 父章节ID
     * @return 下一个可用的序号
     */
    Integer getNextSort(Integer courseId, Integer parentId);

    /**
     * 根据名称搜索章节
     *
     * @param courseId 课程ID
     * @param name 章节名称（模糊匹配）
     * @return 章节列表
     */
    List<Chapter> searchChapters(Integer courseId, String name);

    /**
     * 获取章节的层级
     * 根章节为1，子章节为2，依此类推
     *
     * @param id 章节ID
     * @return 章节层级
     */
    int getChapterLevel(Integer id);

    /**
     * 获取课程的章节树
     *
     * @param courseId 课程ID
     * @return 章节树结构
     */
    List<ChapterTreeResponseDTO> getChapterTree(Integer courseId);
}